home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / wcl-21.lha / wcl-2.1 / doc / wcl.text < prev   
Lisp/Scheme  |  1992-09-10  |  14KB  |  486 lines
  1.             A TERSE GUIDE TO WCL
  2.  
  3.  
  4. RUNNING WCL
  5. -----------
  6.  
  7. The following development binaries are provied with wcl:
  8.  
  9.     bin/eval - linked with basic CL library.
  10.     bin/wcl -  linked with compiler and CL libraries.
  11.     bin/clx - linked with CLXR5, compiler, and CL libraries.
  12.  
  13. Normally a wcl development binary is run from within emacs. The file
  14. emacs/wcl.el should loaded into emacs and the value of the emacs
  15. variables WCL-ROOT-DIRECTORY and WCL-PATH should be set for your site.
  16. You must also install WGDB and make sure that your path is correctly
  17. setup to run it.
  18.  
  19. After these initial steps, The command m-x run-wcl will start wcl
  20. running under gdb. Once wcl is running, definitions from a lisp file can
  21. be loaded into the running wcl using the command c-m-x.
  22.  
  23. When running wcl directly from the command line, the -m switch allows
  24. you to specify how large you want the heap to be in 1kbyte increments.
  25. The default size is 8192 (i.e - an 8 meg heap).  The -s switch allow you
  26. to specify the size of static space. Once wcl is started, the heap
  27. size is fixed (this should be fixed someday). The heap sizes for
  28. a wcl run using m-x run-wcl must be changed by altering the file
  29. emacs/gdb-init.gdb.
  30.  
  31. After wcl has started, it will load an initialzation file named
  32. ~/.wclinit if it exists.
  33.  
  34.  
  35. LOADABLE SYSTEMS
  36. ----------------
  37.  
  38. Ports of the following systems are provided:
  39.  
  40.     - Cltl2 Pretty Printer - loaded by (load-pprint)
  41.      - PCL: loaded by (load-clos)
  42.     - Logical Pathnames: loaded by (load-logical-pathnames)
  43.  
  44. Refer to the README file or sources for each system for more details.
  45.  
  46. CLX
  47. ---
  48.  
  49. CLX R5 is provided as a library.
  50. GCC has a bug which prevents it from compiling CLX correctly, so CC must
  51. is used instead. Before compiling any files which use CLX functions, 
  52. you must also tell the compiler to use CC:
  53.  
  54. (progn (lisp::initialize-compiler)
  55.        (setf *target-machine* *sparcstation-cc*))
  56.  
  57. TO TEST:
  58. cd to src/clx/test directory
  59. % clx
  60. (in-package "XLIB")
  61. ;;; Compile these files for better performance
  62. (load "hello.lisp") 
  63. (load "menu.lisp")
  64.  
  65. (hello-world "") 
  66. (just-say-lisp "")
  67. (pop-up "" '("chocolate" "strawberry" "asparagus"))
  68.  
  69.  
  70. EXTENSIONS TO CL
  71. ----------------
  72.  
  73. WCL contains some popular extensions to pure CLtl1. 
  74. Refer to the sources and the file lib/rtl/packages/package-setup-info.lisp
  75. for more information.
  76.  
  77.  
  78. DEBUGGING WITH WGDB
  79. -------------------
  80.  
  81. A slightly modified version of WGDB is used as the debugger for both C
  82. and Lisp code.  It's best to run WGDB from within emacs using m-x gdb.
  83. Using WGDB with WCL is best explained with a few examples:
  84.  
  85. file foo.lisp
  86. --------------
  87. (in-package "USER")
  88.  
  89. (defun top (x)
  90.   (middle x))
  91.  
  92. (defun middle (x)
  93.   (bottom x))
  94.  
  95. (defun bottom (foo-bar)
  96.   (+ foo-bar 2))
  97. ------------
  98.  
  99. First we'll see how WGDB debugs interpreted code by loading foo.lisp and
  100. calling TOP with a string rather than a number:
  101.  
  102. > (load "foo.lisp")
  103. #P"/usr/home/wade/w/current/test/foo.lisp"
  104.  
  105. > (top "bad arg")
  106. Error: "bad arg" is not a number
  107.  
  108. Program received signal 2, Interrupt
  109. 0xf759c120 in kill
  110. Debug>
  111.  
  112. We can get a backtrace with the WGDB command "bt":
  113. Debug> bt           
  114. #0  0xf759c120 in kill
  115. #1  0xf76ac6a8 in lisp_debug
  116. #2  0xf767c4a4 in ERROR
  117. #3  0xf7675804 in ARITH-ERROR
  118. #4  0xf76a8c54 in add
  119. #5  0xf767a898 in +
  120. #17 0xf76aca7c in BOTTOM (interpreted)
  121. #29 0xf76aca7c in MIDDLE (interpreted)
  122. #41 0xf76aca7c in TOP (interpreted)
  123. #49 0xf76814a0 in REPL-1
  124. #50 0xf76819dc in REPL
  125. #51 0x4cf0 in LMAIN
  126. #52 0x4c5c in RUN-APPLICATION
  127. #53 0x4c88 in main
  128.  
  129. Next we can go directly to a specific frame number with the WGDB "frame"
  130. command. The frame numbers are not always contiguous when debugging
  131. interpreted code because WGDB is hiding evaluator frames which we normally
  132. do not want to see. If we do want to see them, the new WGDB "hide" command
  133. toggles hiding of interpreter frames. For now we'll go directly to
  134. the frame for BOTTOM:
  135.  
  136. Debug> frame 17       
  137. #17 0xf76aca7c in BOTTOM (interpreted)
  138.  
  139. We can now walk up and down the stack with the WGDB "up" and "down"
  140. commands. Notice that these commands skip hidden frames:
  141.  
  142. Debug> up
  143. #29 0xf76aca7c in MIDDLE (interpreted)
  144. Debug> up
  145. #41 0xf76aca7c in TOP (interpreted)
  146. Debug> down
  147. #29 0xf76aca7c in MIDDLE (interpreted)
  148. Debug> down
  149. #17 0xf76aca7c in BOTTOM (interpreted)
  150.  
  151. Now that we are back in BOTTOM, we can use the new WGDB "eval" command
  152. to enter an inferior read-eval-print loop in the lexical environment
  153. of the current frame. This is especially useful for debugging, because
  154. all variables are available by name:
  155.  
  156. Debug> eval    
  157.  
  158. Call: (BOTTOM "bad arg")
  159. Entering debug evaluator. Type :A to exit
  160. Evaluating forms in the current frame's lexical environment
  161.  
  162. Eval:1> foo-bar   ; look at the value of the argument BOTTOM
  163. "bad arg"
  164.  
  165. Eval:1> (inspect foo-bar)
  166. Inspecting a SIMPLE-STRING at address #x48E35D
  167.  
  168. [0] #\b
  169. [1] #\a
  170. [2] #\d
  171. [3] #\Space
  172. [4] #\a
  173. [5] #\r
  174. [6] #\g
  175.  
  176. Command (:H for help): :q
  177.  
  178. "bad arg"
  179.  
  180. Eval:1> :a
  181. $3 = -143023479
  182.  
  183. :A aborts from the inferior read-eval-print loop back to WGDB. At this
  184. point we can simply abort the entire computation with the new
  185. WGDB "abort" command:
  186.  
  187. Debug> abort
  188. Aborting to top-level
  189. Continuing at 0xf76ac684.
  190.  
  191. Compiled code can also be debugged in a similar manner.
  192. WGDB will automatically update its symbol table when an object
  193. file is dynamically loaded into the underlying Lisp process:
  194.  
  195. > (compile-file "foo")
  196. #P"foo.o"
  197.  
  198. > (load *)
  199. #P"/usr/home/wade/w/current/test/foo.o"
  200.  
  201. > (top "bad arg")
  202. Error: "bad arg" is not a number
  203.  
  204. Program received signal 2, Interrupt
  205. 0xf759c120 in kill
  206. Debug> bt
  207. #0  0xf759c120 in kill
  208. #1  0xf76ac6a8 in lisp_debug
  209. #2  0xf767c4a4 in ERROR
  210. #3  0xf7675804 in ARITH-ERROR
  211. #4  0xf76a8c54 in add
  212. #5  0xf6eec17c in BOTTOM at foo.c:51
  213. #6  0xf6eec11c in MIDDLE at foo.c:41
  214. #7  0xf6eec080 in TOP at foo.c:31
  215. #15 0xf76814a0 in REPL-1
  216. #16 0xf76819dc in REPL
  217. #17 0x4cf0 in LMAIN
  218. #18 0x4c5c in RUN-APPLICATION
  219. #19 0x4c88 in main
  220. Debug> frame 5
  221. #5  0xf6eec17c in BOTTOM at foo.c:51
  222. Source file is more recent than executable.
  223. Debug> up
  224. #6  0xf6eec11c in MIDDLE at foo.c:41
  225. Debug> up
  226. #7  0xf6eec080 in TOP at foo.c:31
  227. Debug> down
  228. #6  0xf6eec11c in MIDDLE at foo.c:41
  229. Debug> down
  230. #5  0xf6eec17c in BOTTOM at foo.c:51
  231.  
  232. We can walk the stack just as we did earlier, but this time GDB shows
  233. us the name name of the C file and the line number of our compiled
  234. code. You will also see the corresponding C code displayed in another
  235. window if you are using WGDB under emacs.  Notice that WCL library
  236. functions such as ERROR have not been compiled with debugging
  237. information. The WCL library can optionally be compiled with debugging
  238. information if it is desired.  Refer to the installation documentation for
  239. more details.
  240.  
  241. WGDB currently cannot debug compiled Lisp code at the Lisp source
  242. code level.  However, it can debug compiled Lisp code at the C source
  243. level using any existing WGDB commands such as break, step, etc.
  244. as well as the new WGDB command "lp", which prints the value
  245. of a variable as a Lisp expression:
  246.  
  247. Debug> lp v_FOO_2DBAR_0 ; use the mangled Lisp name displayed in source window
  248. "bad arg"
  249. $1 = 4706509
  250. Debug> eval ; or: "eval v_FOO_2DBAR_0" and * is bound to the value of FOO-BAR
  251.  
  252. Entering debug evaluator. Type :A to exit
  253. Evaluating forms in the null lexical environment
  254.  
  255. Eval:1> (+ 1 2)
  256. 3
  257.  
  258. Eval:1> :a
  259. Debug>
  260.  
  261. Notice that the "eval" command still works with compiled code, but
  262. unfortunately it does not have access to the current lexical
  263. environment (although it could be reconstructed), so the null lexical
  264. environment is used instead. Eval also accepts a variable name as an
  265. optional argument, and will bind the Lisp symbol "*" to the value of
  266. that variable upon entering evaluator. As before we can abort back to
  267. top-level:
  268.  
  269. Debug> abort
  270. Aborting to top-level
  271. Continuing at 0xf76ac684.
  272.  
  273. > 
  274.  
  275. The new "abort" command is also useful if Lisp is in the middle of a
  276. long computation or an infinite loop that we could like to end:
  277.  
  278. > (loop for i from 1 to 1000 do (format t "Iteration ~D~%" i))
  279. Iteration 1
  280. Iteration 2
  281. Iteration 3
  282. ...
  283. Iteration 81
  284. Iteration 82  
  285. ;;; type control-c
  286.  
  287. Program received signal 2, Interrupt
  288. 0xf75722d8 in write
  289. Debug> bt
  290. #0  0xf75722d8 in write
  291. #1  0xf7573a58 in _xflsbuf
  292. #2  0xf757382c in _flsbuf
  293. #3  0xf75a685c in fputc
  294. #4  0xf7670630 in WRITE-CHAR/FPTR-STREAM
  295. #5  0xf7670670 in WRITE-CHAR/TERMINAL-STREAM
  296. #6  0xf7670360 in WRITE-CHAR/2
  297. #7  0xf7686e44 in TERPRI
  298. #8  0xf7651de0 in FORMAT-TERPRI
  299. #9  0xf764c128 in SUB-FORMAT
  300. #10 0xf764b580 in FORMAT
  301. #31 0xf76aca7c in (LAMBDA (I) ...) (interpreted)
  302. #39 0xf76814a0 in REPL-1
  303. #40 0xf76819dc in REPL
  304. #41 0x4cf0 in LMAIN
  305. #42 0x4c5c in RUN-APPLICATION
  306. #43 0x4c88 in main
  307.  
  308. After interrupting the loop, we can continue it with the WGDB
  309. "continue" command:
  310.  
  311. Debug> continue
  312. Continuing.
  313. Iteration 83
  314. Iteration 84
  315. Iteration 85
  316. ...
  317. Iteration 289
  318. Iteration 290
  319. ;;; type control-c again
  320.  
  321. Program received signal 2, Interrupt
  322. 0xf75722d8 in write
  323. Debug> 
  324.  
  325. We interrupt the loop again and abort to top-level with the 
  326. "abort" command:
  327.  
  328. Debug> abort
  329. Aborting to top-level
  330. Continuing at 0xf76ac684.
  331.  
  332. > 
  333.  
  334. The new commands "info restarts" and "restart" allow WGDB to interact
  335. with the CL condition system.
  336.  
  337. Ultimately, WGDB should be modified to provide full source level
  338. debugging of Lisp code.
  339.  
  340.  
  341. LINKING APPLICATIONS AND SHARED LIBRARIES
  342. ------------------------------------------
  343.  
  344. Here's a quick example of how to compile and link an application
  345. consisiting of two files:
  346.  
  347. file bar.lisp:
  348. ---------------------
  349. (in-package "USER")
  350.  
  351. (defstruct point x y)
  352. ---------------------
  353.  
  354. file foo.lisp:
  355. ---------------------
  356. (in-package "USER")
  357.  
  358. (defun lmain ()
  359.   (format t "Point: ~S~%" (make-point :x 3 :y 4)))
  360. ---------------------
  361.  
  362. In WCL:
  363.  
  364. > (compile-file "bar")
  365. Compiling file #P"bar.lisp"
  366. Wrote object file #P"bar.o"
  367. #P"bar.o"
  368.  
  369. > (compile-file "foo")
  370. Compiling file #P"foo.lisp"
  371. Wrote object file #P"foo.o"
  372. #P"foo.o"
  373.  
  374. >  (link-executable '("foo" "bar"))
  375. 0 seconds: Reading symbol information
  376. 1 seconds: Compiling predicates file
  377. Compiling file #P"/n/kobold/usr1/home/wade/tmp/26123-23preds.lisp"
  378. Wrote object file #P"/n/kobold/usr1/home/wade/tmp/26123-23preds.o"
  379. 4 seconds: Writing data file
  380. 4 seconds: Compiling data file
  381. 10 seconds: done
  382. #P"foo"
  383. >
  384.  
  385. Now we can run it from a shell:
  386.  
  387. /home/wade/test> strip foo
  388. /home/wade/test> size foo
  389. text    data    bss    dec    hex
  390. 40960    8192    0    49152    c000
  391. /home/wade/test> foo
  392. Point: #<POINT 64ADD>
  393. /home/wade/test> 
  394.  
  395. The file src/build/library-definitions.lisp contains more examples of
  396. how to link applications and shared libraries.
  397.  
  398.  
  399. THE COMPILER
  400. ------------
  401.  
  402. The compiler is controlled by setting up different configurations.
  403. refer to com/common/configurations.lisp for more information.
  404. PROCLAIM is the CL approved way to change configurations.
  405.  
  406. Array and numeric declarations are used by the compiler to translate
  407. Lisp array operations and some numeric operations directly into 
  408. equivalent C constructs. Dynamic-extent &rest lists are supported, as
  409. are &restv lists.
  410.  
  411.  
  412.  
  413. GARBAGE COLLECTION
  414. ------------------
  415.  
  416. The currently collector is based upon the ideas described in Joel
  417. Bartlett's mostly-copying conservative gc. A single heap area and a
  418. single static area are used for allocating memory at runtime.
  419. Statically allocated data can also be located in the data segment of
  420. a program and any shared libraries that it uses.
  421.  
  422. The GC should eventually be changed to become generational.  Doing
  423. this could also provide Lisp a general mechanism for setting pointers
  424. in statically allocated objects. Currently we have to keep track of
  425. static objects and scan them.
  426.  
  427. Note that it is possible for a C compiler to generate code which uses
  428. derived or offset pointers, and thus is not safe for garbage
  429. collection. This can be big trouble, but Sun cc and gcc don't *seem* to
  430. have this problem (i.e - they're not that tricky).
  431.  
  432.  
  433. FOREIGN FUNCTION CALLS
  434. ----------------------
  435.  
  436. The macro DEFFOREIGN is used to tell Lisp how to call foreign
  437. functions:
  438.  
  439.   (defforeign unlink ((path char*) => (status int)))
  440.  
  441. The foreign function interface is incomplete and needs more work.
  442. Refer to other examples of how DEFFOREIGN is currently used in the
  443. system for more information.
  444.  
  445. Calls from foreign code back into Lisp work equally well, but no
  446. formal support for them exists. In other words, you need to know the
  447. mangled name of the Lisp function you want to call, pass an argument
  448. count, and perform any data conversions yourself.
  449.  
  450. The macro DEF-C-STRUCT is also useful for describing the layout
  451. of foreign structures to Lisp.
  452.  
  453.  
  454. PORTING WCL
  455. -----------
  456.  
  457. The dynamic file loader is the most operating system and machine
  458. dependent part of the system. Currently the dynamic file loader
  459. only works for SPARCS running SunOS 4.1.
  460.  
  461. Every machine has a corresponding machine configuration structure
  462. in the compiler.
  463.  
  464. These parts of the system are written in assembly language, and
  465. thus are processor specific:
  466.  
  467.     - Closure allocation and closure garbage collection.
  468.  
  469.     - Fixnum arithmetic handling. Fixnum arithmetic must overflow
  470.           into bignums correctly. On SPARC this is done with an explicit
  471.           overflow check, and on MIPS it is done by the signal handler.
  472.  
  473.     - The garbage collector needs a machine dependent routine to put any
  474.           registers not normally saved by the C calling convention into a
  475.           stack allocated vector.
  476.  
  477. The actual amount of assembly code is small (perhaps a few dozen lines).
  478.  
  479. Generic bignum code is available, but machine specific bignum routines
  480. are also available for a variety of machines.  All the sources are in
  481. the bignum directory.
  482.  
  483. p.s - There's lots of stuff I haven't put in this document. Send
  484. mail to wade@sunrise.stanford.edu if you have a question.
  485.  
  486.